Query Builder utility
Query Builder is available in version 16.5 Update 10 and later.
This is a web-based tool for easier construction of complicated OData API request strings. The current version covers only the OData requests for periodic or scalar data from Economics result sets in 'wide' table format, i.e., based on the API requests '/PlanningSpaceEconomics/Data/V1/AllPeriodicVariablesWide' or '/PlanningSpaceEconomics/Data/V1/AllScalarVariablesWide'.
Note that the tool does not process API requests. To do that you need to use a data-oriented client tool such as Excel Power Query or Power BI, or a general-purpose API client tool. See Integration Services (OData); Power BI and OData.
To access the tool you need to login with a PlanningSpace user account and this account's access permissions for Economics data will determine the data that you will be able to access when using the tool (i.e., it is equivalent to making OData API requests with authentication using that user account).
Access to Query Builder
Query Builder is a web-based application that is included in the PlanningSpace tenant web server.
To access the tool, login to the web site for the PlanningSpace tenant, for example 'https://ips.mycompany.com/tenant1'. At the login screen, use an appropriate user account, which has permissions to access the Economics result set data that you are interested in.
You should see a Query Builder button, as shown in the following screenshot:
Click the button and the Query Builder screen should appear:
You can return to the tenant home web page by clicking the User menu at the top-right corner of the screen, and selecting the All applications option.
Using Query Builder
There are three panels where data are selected, and each selection adds parameters to the API query text at the bottom of the window.
Use the Reset button to cancel all data selections and settings, and the Copy to clipboard button to copy the API query text to the clipboard.
By default the periodic variable API request 'AllPeriodicVariablesWide' will be used.
For version 16.5 Update 11 and later: All of the default metadata columns are included in the '$select' list (in previous versions, some were omitted); unwanted columns should be removed in the tool output. Also, variables will be included in '$select' in alphabetical order (previously, the ordering was based on the time order in which the check boxes were clicked).
Result Set
The first panel Result Set shows a list of the result sets that are permitted to be read by the current user account (this could be empty), with Result Set Name and Folder Path columns. Filters can be applied to either or both columns.
One Result Set must be selected (by clicking its name).
For version 16.5 Update 17 and later: there is an improved 'tree view' interface which displays the available Result Sets. You can use the Search Result Set... field to search: the string that you enter will be matched against the initial characters of Result Set names (i.e., 'names starting with...'; note that folder names are not matched).
Optionally, one or more Result Set Runs can be specified. If not, the API query will return data for all Runs.
Also optionally, one or more Partners can be specified. If not, the API query will return data for the 'Gross' partner only.
Variables
Click the Variables button to open that panel. Either Periodic or Scalar variables can be displayed, and this selection also selects the API request as 'AllPeriodicVariablesWide' or 'AllScalarVariablesWide'. The default selection is Periodic.
You can filter the variables list in several ways. The filter box at the top (Type to filter the variable grid...) performs simple substring text matching on text in any of the table columns. For more sophisticated filtering you can use one or more of the filter buttons at the top of the table columns.
For version 16.5 Update 17 and later: There is an optional filter on the variables list when a Result Set is selected: Filter variables by selected Result Set: {NAME}. If the filter is enabled, only variables that are used in that Result Set will be listed.
For version 16.5 Update 15 and later:
There is an added column (with the
header 
)
which contains a 'favorite' flag for each variable.
The favorited variables are separately-stored for the Periodic and
Scalar variable tables.
If you mark a variable as a favorite
(
)
this information will be stored
for future use. Hence you can mark a group of variables and quickly access them in future Query Builder sessions;
if you click the favorite column header you can sort on that column and bring the favorited variables to the top of the table.
Important: the favorites information is stored in the 'local storage' of the browser program, therefore you must use the same computer and same program to access the stored information. The browser 'localStorage' data will be maintained until the browser's cached information is cleared; you can intentionally clear the information using the browser <F5> general reset, or by a specific deletion in the browser's 'Privacy & Security' settings.
The favorited variables are specific to each server/tenant URL that you connect to, but they are not specific to different PlanningSpace user accounts that you use to login to PlanningSpace.
Settings
Click the Settings button to open that panel. All of these settings are optional overrides which will cause the result set data to be transformed when it is returned in the API response. The data retrieval will be based on defaults which are explained in the panel.
When the API query building has been completed, you can use the Copy to clipboard button to copy the API query text to the clipboard.
Query Builder does not process API requests. To do that you need to use a data-oriented client tool such as Excel Power Query or Power BI, or a general-purpose API client tool, as explained elsewhere in this document. See Integration Services (OData).
Disconnecting from the tool
To disconnect from the tenant web site, click the User menu at the top-right corner of the screen, and select Log out.
For safety, there is an automatic logout when the interface is idle (the default idle time is 15 minutes).